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1. Glossary 
In order to facilitate understanding, we have listed below a small glossary with the main 
terms related to pre-postage. 





Term Description 





Authentication Process of verifying a user's digital identity, which means, to ensure that the user 


is really who he says he is. 











Authorization Process of verifying which are the given privileges to use an application. 
Postage card Card that identifies a user as a Correios Contract customer. 
Service Code Code of the services contracted by the customer along with Correios. The 


contracted service codes are included in the commercial contract that the customer 
has signed with Correios. 























Commercial Document that the customer signs with the Correios for the provision of services 
Contract of parcels, messages, direct marketing and others. 

Meu Correios Authentication and authorization mechanism for accessing the services that 
(My Correios) Correios makes available through the internet. 

Component's Meu Correios' user-defined password that allows a user to use the components 
Password provided by Correios. 

Token - Api | Token generator system for API access. Generates an encoded string in order to 
Manager ensure the security of whoever is using the API and to prevent fraud. 
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2. Introduction 


This material was developed to contribute to the planning and integration with 
Correios in any platform desired by the customer. 

For those who want to integrate with Correios, we present the Correios API, that 
shows which components are released for use by the customer. The components covered 
in this material are APIs, developed in REST and using the HTTP protocol. Which means, 
a base url will be provided and the HTTP verbs will indicate which action is being requested 
by the client. 

Finally, the access to the Correios API is one of the benefits of Correios' commercial 
policy. 
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The access to APIs must be performed through the Correios API catalog. In the 
catalog the customer will be able to test and follow the changes when they happen. The 
catalog is available in the Homologation and Production environment: 


e Homologation: https://cwshom.correios.com.br/ 


e Production: https://cws.correios.com.br/ 





€ co O À https //ow correios.com.br/dashboard/pesquisa 10%) "UY km e = 


= @ Correios © O 5 
Correios Web Services E 

(CWS) O Credenciais @ | 

Início Api Manager - Token (5) x © 


Documentacáo 


Gestáo de acesso a Token € O 


componentes https:/fapihor 











Ajuda 
Token "raan de to 





| POST /v1/autentica Gera um token para acesso a APIs | 








| POST /vl/autentica/cartaopostagem Gera um token para usuários externos (idCorreios) | 





Schemas Vv 


CartaoPostagem > 








Knowing the Correios Web Services' screen: 

1. Clients name, option's list to access Meu Correios, exit environment and other 
configurations; 

2. Hamburger button, opens the lateral menu and allows you to access the 
documentation and component's access management; 

3. Search bar and credentials generator button, the search bar shows a component's 
list that you are allowed to access. The credentials button allows you to generate the 
token to do the request's attempt through the site; 

4. Component tab, the content of each bar shows the API name, version and a link to 
the api-docs. Just below the title, or the group, shows the verb of the request. Clicking 
on the verb “POST” opens a place where tests can be carried out by the browser 
using the “Try-it out” functionality. 


Business Board — Sup. of Digital Channels 


Review 03/24/2022 6 


D correos 
P API 


Correlos Integration Guide 


4. Requisites to use Correios API 


e Must have a valid registration in the Meu Correios; 

e To access the API, you use a password defined for the component, to create the 
password you must access the Correios API; 

e Must have an active contract for the provision of parcel or message services with the 
Post Office; 

e Companies that provide IT solutions in the logistics segment. (How to identify and 


provide access?) 


5. Acess to the APIs. 
The Correios' APIs come with access rules as follows: 
e Public API: Where everybody sees the API; 
e Restrict API: The access is made from the service registration in the postage 


card on. 


Each contract has its particularity to better serve each client. In order to take a look 


atthe released APIs on your profile, simply click on the search bar and see what is available. 





Credenciais dé | | Digite o nome ou código da api Para pesquisa 














Preencha este campo. 





Abrangência CWS (237) 





Api Manager - Token (5) 
Mensagem Digital - Ext (83) 
Objetos Postados CWS (242) 


Pré-atendimento REST (418) 





post card. 
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In order to make the restricted APIs visible, you must include the data as below: 


User credentials, 









Informe as credenciais de acesso 


E e 


O usuário é obrigatório 


= O 


A senha é obrigatória 


Cartáo de Postagem: 
79 O 


Para acesso a APIs com autorização pelo cartão de postagem. 


Password, 





Postage card, 





Generate Token and 















Mr M M e 


Close. 








Token: 





ey JhbGci0iJSUZUxMiJ9.ey IW JpZW50ZSI6IkhPTUIMTOdBQ 
OF PliwiaWQIO1JIbXByZXNhY3dzlIwicGZsI joiUEoILCJjbnBqljot 
MzQwMjgzMTYwMDAXMDMILCJhcGkiOlszNiw1 MIZ AC IT 
WB8tcG92dGFnZWOiOnsibnVtZXJvijolMDAZNZUSOTAZOSIsIMNv 





bNRyYXRvijoiOTK5MjE1NZg4MCISIMRyljoxMCwiYXBplipbODAs 





OTMsMzYSNTcsODcsODNdfSwiaXAiOilxMC44_jYOLjYxLDEwLjQ 
L_3LiAuMCwxMC4AL VOL ¡Y x! gza 3. 








he 





See that now the following APIs appears: 
e Agência (Agency); 
e Endereço — CEP v3 (Address — CEP v3); 
e Prazo (Deadline); 
e Preço (Price); 
e Rastro (Track). 








| bigite o nome ou código da api para pesquisa 
gs mm 
Agéncia (76) 


Api Manager - Token (5) 
Dir. "mg 
C= 8 
Endereco - CEP v3 (41) 
g- r~e 1 4 
us. tm + 
l'ont Me tags œ 
Preço e Prazo - Prazo v3 (35) 
house fun fous wem 22 
Preco e Prazo - Preco v3 (34) 
SRO - Rastro (87) 
eee om 
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For the first test, it will be with the generation of the Token, an API without restriction 
and necessary in the generation of an encoded string with the authentication and 


authorization data to inform the APIs of the Correios. 
When click on “POST”, it will appear the sub-item Parameters and to enable the 


environment, just click on “Try it ou? button. 


Token OD) 
com 


https://apihom.correios.com,brítokenv3/api-docs 


Token Geração de tokens para acesso de APIs 


POST /v1/autentica Gera um token para acesso a APIs 


/v1/autentica/cartaopostagem Gera um token para usuári 

















Para acessar APIs cuja autorização seja por cartão de postagem. 


Parameters 





No parameters 





application/son 











Request body 


Example Value | Schema 











After clicking at the button, the screen will allow you to input the postage card (1) and 


click at “execute”. 








Para acessar APIs cuja autorização seja por cartão de postagem. 


























After execute, there will be a server answers, just roll the page down, until the sub- 
item Responses. 

On item 1: Curl used commands or commands script, among it is the requisition verb, 
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at this case, “POST”; 
On item 2: Requisition URL; 
On item 3: Code 201 — Created, where the return Body contains the return in JSON. 


Responses 


Request URL 2 


https://apihom.correios.com.br/token/vi/autentica/cartaopostagem 





Server response 


Code O Details 


201 
0 Response body 


"cartaoPostagem": { 
“numero”: C 
"contrato": "IMA 


control: no-cache,no-store,max-age=0,must-revalidate 
t-type: application/json 
0 


pragma: no-cache 





On the token's requisition body we will have: environment, id, profile, contracts data, token's 
expiration date and the token. 
Be mindful to the token's expiration date. 


See the return of request example: 





Data related to the 1 
postage card "ambiente": "HOMOLOGACAO", 
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Token's expiration 


"id": 2000000000", 
"perfil": "PJ", 
"cnpj": "00000000000101", 
"cartaoPostagem": { 
"numero": "OOXxxxxxx7", 
"contrato": "99xxxxxxxx”, 
"dr": 10, 

"api": [ 

93, 

36, 

83 





date (“expiraEm”) 





Token 


"emissao": "2022-03-18T10:26:51", 
"expiraEm": "2022-03-19T10:26:51", 








eyJhbGciOiJSUZUxMiJ9 
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Exploring the bottom of the Token tab page, we will find the Schemas Group, where 


you can view the properties. 


Schemas Vv 


CartaoPostagem > 
Token > 


CartaoPostagemRequest v ( 
description: Cartao de postagem. 
numero string 


L 


MessageResponse > 
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6. API Characteristics 


The Correios APIs was developed with REST technology, besides of being a market 
standard, it allows you to choose or adopt which programming language you can use, such 
as: ASP, .Net, Java, PHP, Ruby, Python, among others. 


Among other characteristics, the features that stand up the most at API are: 


e Absence of proprietary applications: There is no need to install a specific 
environment to use the API. 
e Simplicity: The protocol used is purely the HTTPS. 


e Credentials: The treatment of client’s credentials transit in a secure environment. 
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7. Correios APls 


The Correios API is a micro-services-oriented architecture allowing to develop 


systems that are more flexible, scalable and with simpler maintenance. 


10) Correios API 


= 


Busca CEP Rastreamento Prego e Prazo Busca Agéncia 
(ZIP Code @ de Objetos (Price and (Find a Post 
Search) (Tracking) Delivery Time) Office) 





As the volume of requests may vary from 1 or hundreds of requests, to obtain a quick 
response from the Correios server we are adopting two forms of request: the synchronous 


form and the asynchronous form. 


The difference between synchronous and asynchronous: 
e Asynchronous request must wait for the completion of processing and can only 
make a new request after the request is answered, this action may give the feeling 


of freezing the request. 


e In an asynchronous request, the client sends a request and receives data that 
allows querying the processing status. This allows to perform new asynchronous 
requests, without the need to wait for the other requests to finish processing. At 
the end, you will be able to request the collection of the data that has been 


processed. 
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8. Preparing the environment on Postman 


To start the tests, without a tool in which you can save what was developed, it can 
generate rework. For this purpose, in this manual, we will use the Postman tool that allows 


us to carry out the tests and, most importantly, save the work. 


In addition to downloading the tool, you can use an extension through the Google 
Chrome browser, adding the Postman extension. There are other tools, such as Insomnia. 
You can use the tool of your choice. 





© Postman — D x 
File Edit View Help 
~ = > A A 
Home Workspaces API Network Reports Explore Q, Search Postman oS S SS Q O Upgrade 
PA manual_homolgoacao New Import Overview No Environment 
5 = 
electors + manual_homolgoacao 
Media Authentication AF Get started 
E E ma En Create a request 
In this workspace < 
[3 Create a collection 
a flee Road 0 0 0 0 0 o 
Mock do Create an API 
g TE T 
bd IS) Create an environment 
Create a collection for your requests Activity 
E View More 
A collection lets you group related requests and User v Entity v Refresh 
ea t pts 
Today Sharing 
Visibility 
Create collection O Gustavo Nagata created this team workspace 
A Team 
a d 
I ti orksp Admin 
Members and groups Invite 
É vou dmin 
EI Qin Rer a & Bootca E Runner H Trash 


We clarify that the adoption of Postman is for educational purposes only, 
considering that it facilitates the understanding of the steps to access the APls 
provided by Correios. 
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B. Creating a collection 

The collection allows you to separate the API that will be used throughout the 

manual, which can be used to separate the process. Such as: Token Generation, 


Pre-Post Generation, Label Generation, etc. Click on the “+” and a collection will 


appear that says "New Collection". 


W A S 


Create new Collection 


Collections 





Click on “New Collection” and, at the right side, click on the pencil icon, at the right 


side of the name. 


New Collection Am 2 


Tests Variables 


Auth  Pre-reg. 





Write the collection's name, for instance: “Geração do Token” (Token 


Generation). 






Geração do Toke) © 0 $ 


Auth Pre-req. Tests Variables 


Business Board — Sup. of Digital Channels 
16 


Review 03/24/2022 


» CORREIOS 
API 


» 
« Integration Guide 


Correios 
C. Creating the request 


To create a request, after creating a collection, click on “Add a request”. 


» Geração do Token 


This collection is empty 
Add a h to start working. 





At the right side, a tab will open, where you could rename it to “Gerar token para 


o cartão de postagem” (Generate token for the postage card) 





Geração do Token / Gerar token para o cartão de postagem $ 2 


= o oia EN 


Pre-req. Tests Settings Cookies 


Params Auth Headers (6) Body 
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Generate token for the postage card 
D. Knowing the screen 
Item 1: Navigation tabs; 
Item 2: Name of the request and which collection it belongs; 
Item 3: Verb and the url base; 
Item 4: Information that can be added by parameters, authorization data, request's 
head, request's body. 
Item 5: Send button, if you press the down arrow, you will be able to send and to 
download the result; 


Item 6: Response. 








No Environment {v 


KEY VALUE DESCRIPTION coo Bulk Edit 


Key Value Description 








Enter the URL and click Send to get a response 
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It is necessary to use the information shown in the Correios API, in order to fill 
in the request's fields: 
Recapitulating, in the previous steps we saw: 
e Access to the components: Login and password to access components; 
e Request address ; 
e Verb used in the request; 
e Request body. 
For this first example, the following image shows the (1) main address that 


will be used, (2) the verb and (3) request address. 


Api Manager - Token (5) x 







Token ED E 
https://apihom.correios.com.br/tokeniv3/api-docs © 


Servico de token para acesso das APIs 


Token Seração de tokens para acesso de APIs 


| POST /vl/autentica Gera um token para acesso a APIs 


3 
PS? vl/autentica/cartaopostagem Gera um token para usuários externos 


In this way, the address that will be used in the request is the junction of the 














main address (1) and the request address (3). Example: 
httos://apihom.correios.com.br/token/v1/autentica/cartaopostagem. 





At the request address and at the verb will be like this: 


Gerar token para o cartáo de postagem E Save v 000 Ê 


POST v https://apihom.correios.com.br/token/v1/autentica/cartaopostagem EN 
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At login and password, click on the tab (1) Authorization, select the Type (2) 


“Basic Auth” and (3) fill in the data of login and password: 


Geração do Token / Gerar token para o cartão de postagem [E Save + | 
POST v https://apihom.correios.com.br/token/vi/autentica/cartaopostagem 
Authorization e Headers (9) Body Pre-request Script Tests Settings 
Type Basic Auth x © Heads up! These parameters hold sensitive data. To keep this data secure while working in a collaborative environmen 
using variables. Learn more about variables 2 


The authorization header w Inherit auth from parent 
generated when you send 1 


Learn more about authorize No Auth sername 
API Key 
assword 


Bearer Token 
Basic Auth hy Show Password 


Digest Auth 





The next step consists to send the postage card's data, click on (1) Body, (2) 
raw, (3) JSON and (4) paste the JSON from Correios Web Services homologation 


site. 


POST e https://apihom.correios.com.br/token/v1/autentica/cartaopostagem 


Params Authorization e Headers (10) Body e O Script Tests Settings 





none form-data ) x-www-form-urlencoded @ raw binary Z GraphQL JSON v © 


1 à 


| 
2 | “numero”: " 19" O 
3 È 





Click on “Send” and see the return: 


POST» | ehren com ioanvilmnenicalcartspostagem EN 


Params  Authorization@ Headers DÉI  Bodye  Pre-tequestScript Tests Settings 


form-data @ x-www-form-urlencoded @raw @ binary @ GraphQl JSON ~ Beautify 





Based on this step-by-step, you will be able to replicate to any API. 
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The CEP (Zip Code) is a numerical set consisting of eight digits, which guides and 
accelerates the forwarding, processing and distribution of correspondence objects, through 


Integration Guide 


their assignment to locations, public places, Post Office units, services, public agencies, 


companies and buildings. (To learn more: All about CEP) 


The tests can be ran through the Correios API page, as follows: 


Endereço - CEP v3 (41) x 








CEP v3 €D CD 


https:/lapihom.correios.com.bricepWv3/api-docs 


API de busca CEP. 


Endereço Endereco v 





| /v1/enderecos Consulta os endereços de uma lista de ceps de no máximo 20 itens. 


| /v1/enderecos/(cep) Consulta o endereço de um CEP. | 


| /v1/enderecos/intervalo Consults os endereços pertencentes a um intervalo de CEPs. 

















Or through Postman: 





In this example, the method that requires the value to query the address of a zip code 
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will be used. 


The base url is: 'https://apihom.correios.com.br/cep/ ' and, according to the 
documentation, that will be a GET : “/v1/endereços/fcep)”. 

Note: By default the zip code is formed by 8 numeric digits, but for some addresses 
we use the O (zero) on the left, example: 01001001. 


To the request: 





curl --location -- 





request GET 'https://apihom.correios.com.br/cep/vi/enderecos/01001001! A 
--header ‘Accept: application/json' A 

header ‘Authorization: Bearer eyJhbGciOiJSUzUxMiJ9.eyJhbWIpZW50ZSI6IkhPTUIMTOABO 
OFPLiwiaWQi0iI1MzQ20DQOMDAWMDEZNCIsInBmbCI611BKTiwiY25wail61jUzNDY4NDQwMDAwMTMOI 
iwiY2FydGFVLXBvc3RhZ2VtIjp7Im51bWVybyI 61jAwNzYzNjI2MzkiLCJjb250cmFObyI61jk5MTIOM 
jJAyOTIiLCJkcil 6MTAsImFwaS16WzQxLDc2LDM0LDM2LDM1LDg3LDgzLDI2XX0sImlwIjoiMTAu0C42N 
C42MSwxMC4z0C4WwLjASsMTAUOC42NC42MSIsImlhdCI6MTYONZY5MzkzOSwiaXNzIjoidG9IrZW4tc2Vyd 
m13ZSIsImV4cCI6MTYONZC4MDMzOSwianRpIjoiN2ZmNTAOMGUtOWV3MSOONTAyLTh3]NGUtYzM5Yzk30 
WYOOTNjIn0... 





























The response will be: 











{ 
"cep": "01001001", 
ue "SPT; 
"localidade": "São Paulo", 
"logradouro": "Praça da Sé", 
"tipologradouro": "Braga", 
"nomeLogradouro": "da Sé", 
"complemento": "- lado par", 
"abreviatura": "Pç da Sé", 
"bairro": "sé", 
"numeroLocalidade": 96681, 
"ELDOCER": 2, 
"cepUnidadeOperacional": "01032970", 
tado": Et, 
"numeroInicial": 0, 
"numeroFinal": 998 

} 
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In case of exception, there is the return http 400 from server such as the following 
examples: 


In case of non-existing CEP (zip code): 












Body Cookies (1) Headers (13) Test Results (ES Status: 404 Not Found Time: 636ms Size: 524 B Save Response v 
Pretty Raw Preview Visualize JSON + = B A 
1 E | 
2 "cep": "01001011", 
3 "txMsg": "CEP-003: O CEP 01001011 não foi encontrado” 
4 Ñ 


In case of non-standard typing: 


In this example, the CEP: 01001-001 was used, with the hyphen. However, the return 
informs the number of characters and the example format. 





Body Cookies (1) Headers (13) Test Results & Status: 409 Conflict Time: 17 ms Size: 8.57 KB Save Response v 
Pretty Raw Preview Visualize JSON v = D Aa 
1 À D 
2 "msgs": [ 
3 “CEP-004: CEP no formato incorreto. 8 dígitos. Exemplo: 70902900" 
4 1, 
5 "date": “2022-03-19T11:06:05", 
6 "path": “uri=/cep/v1/enderecos/01001-001", 
L "causa": "ConstraintViolationException: consultaCEP.cep: CEP-004: CEP no formato incorreto. 8 digitos. Exemplo: 


709902900”, 





10. API Agéncia (Agency/Post Office API) 


The API Search Agency has the functionality of showing the post office units per 


location. There are search mechanisms by post-office units or or by location. 


Api Manager - Token (5) x Agência (76) x 


Agência Open 


https://apihom.correios.com.br/agenciaW3/api-docs 


Unidades 'sentificar agências dos Correios por localidade, permitindo a verificação dos horários de funcionamento e as informações para contato 





GET /v1/unidades Lista todas as unidades de forma paginada 


E 











Tipos de Unidades Recupera os tipos de unidades v 


ERA 








Localidades Recurera as localidades onde existem agências {v 


AAA 








Status Recupera os status existentes nas agências 


AE EEE 

















To use the units query, it is necessary to retrieve the unit types and status data. 
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For the Agency API the base url: “https://apihom.correios.com.br/agencia”, and for the 
example a GET will be used: “/v1/unidades” with parameters. 


Request example: 





curl --location == 





request GET 'https://apihom.correios.com.br/agencia/vl/unidades?status=2&status= 
5&codigoTipoUnidade=0 9&codigoTipoUnidade=12 &codigoTipoUnidade=4 3&codigoTipoUnida 
de=46 &codigoTipoUnidade=24&codigoTipoUnidade=25 &codigoTipoUnidade=27&codigoTipoU 
nidade=16&codigoTipoUnidade=1 8 &codigoTipoUnidade=20 &écodigoTipoUnidade=21&codigoT 





ipoUnidade=24&codigoTipoUnidade=25&municipio=Sao Paulo&bairro=CENTRO&uf=SPépage= 
O&size=50" À 

--header 'Accept: application/json' \ 

header ‘Authorization: Bearer eyJhbGciOiJSUzUxMiJ9.eyJhbWIpZW50ZSI6IkhPTUIMTOABO 
OFPLiwiaWQi0iI1MzQ20DQOMDAWMDEZNCIsInBmbCI6I11BKTiwiY25wail61jUzNDY4NDQWMDAwMTMOI 
iwiY2FydGFVLXBvc3RhZ2VtIjp7Im51bWVybyI 61jAwNzYzNjI2MzkiLCJjb250cmFObyI61jk5MTIOM 
jJAyOTIiLCJkcil 6MTAsImFwaS16WzQxLDc2LDM0LDM2LDM1 LDg3LDgzLDI2XX0sImlw1IjoiMTAu0C42N 
C42MSwxMC4z0C4WwLjASsMTAUOC42NC42MSIsImlhdCI6MTYONZY5MzkzOSwiaXNzIjoidG9IrZW4tc2Vyd 
m13ZSIsImV4cCI6MTYONZCAMDMZOSwianRpIjoiN2ZmNTAOMGUtOWV]MSOONTAyLTh3]NGUtYzM5Yzk30 
WYOOTNjIn0... 





























Response: 





{ 
"itens™: [ 
{ 
“id: "00024419", 


"codigoAntigo"”: 72300019", 
"codigoCadastroGeral": 16439, 
"nome": "AC CENTRAL DE SAO PAULO", 
"ativa": true, 

status": "2%, 

"descStatus": "INSTALADO", 

tipo: CAM, 


"tipoUnidade": { 
"codigo": "09", 
"descricao": "AGENCIA CORREIO", 
"sigla": "AC ICO" 





DÉI 
"emails": [ 
"spmacacp@correios.com.br" 


l, 








"endereco": { 
"cep: "01031970"; 
gets MER, 
"localidade": "SAO PAULO", 
"municipio": "SAO PAULO", 
"logradouro": "PRACA DO CORREIO", 
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"bairro": "CENTRO", 
"numero": "SN", 
"codigolbge": "3550308", 
"regiao": "SDE", 
"longitude"; "—46. 636301", 
"latitude": "-23.544201", 
"uso": "UTE-O03<00", 
"EusoVerao": "UTC=03:00" 
}, 
"horarios": A 
"funcionamento": "SEGUNDA À SEXTA", 
"iniExpediente": "09:00", 
"fimExpediente": "18:00", 
"limitePostagemSemana": "17:35" 
}, 
"eodigoSro": | 
"01008972" 
l, 
"dhAlteracao": "2021-03-16T01:01:22,27" 
tass sl 
“page: d 
"size": 50, 
"totalElements": 7209, 
"totalPages": 145, 
"number": 0 
) 
) 











In this example search, the size attribute informs how many elements per page, a 
size=50 was placed in the request, that is, 50 elements per page, totaling 145 pages. If the 
same query is performed to inform the content of the other pages, just inform the value of 
0..144 in the page attribute, if you keep the size=50. 
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11. API Preço (Price API) and API Prazo (Delivery Time API) 


The search for price and delivery time is separated from each other, to meet 
the concept of micro-services. Thus, it makes two pages in the Correios API catalog. 
API Delivery Time (Prazo) (35): 


Api Manager - Token (5) x Preço e Prazo - Prazo v3 (35) x 


Prazo OO 


https://apihom.correios.com.briprazoN3/api-docs 
Nacional "razo de produtos e serviços nacionais v 


E 111220100227 t0orronto) coca zo da um parao 
DERRETE 

















Internacional Praz de produtos e serviços internacionais. v 
EE 




















For the url base:  https://apihom.correios.com.br/prazo/ using GET: 


/v1/nacional/{coproduto} 





curl --location -- 





request GET 'https://apihom.correios.com.br/prazo/vl/nacional/03220?cepo 
rigem=70002900&cepDestino=05311900' \ 

--header 'Accept: application/json' \ 

header 'Authorization: Bearer eyJhbGciOiJSUzUxMiJ9.eyJhbWJpZW50ZSI6IkhPT 
U9MTOABOOFPTiwiaWQi0iTI1Mz020DQ0MDAWwMDEZNCIsInBmbCI6I1BKIiwiY25wail6IjUzN 
DY4NDOwMDAWwMTMOIiwiY2FydGFvLXBvc3RhZ2VtIjp/7Im51bWVybyI6IjAwNzYzNjI2MzkiL 
CJjb250cmFObyI 617 k5MTIOMJAYOTIiLCJkcil 6MTAsImFwaSI 6WzQxLDc2LDMOLDM2LDM1L 
Dg3LDgzLDI2XX0sImlwIjoiMTAu0C42NC42MSwxMC4zO0C4wLjAsMTAuO0C42NC42MSIsImlhd 
CI6MTYONzZY5MzkzOSwiaXNzIjoidG9rZW4tc2Vydml1jZSIsImV4cCI 6MTYONzc4MDMzOSwia 
NRpIjoiN2ZmNTAOMGUtOWVjMSOONTAyLThjNGUtYzM5Yzk3OWY0OTNjIN0.... 
































We have the following response: 














{ 
"coProduto”: "03220", 
"prazoEntrega": 1, 
"dataMaxima": "2022-03-22T23:58:00", 
"entregaDomiciliar": "S", 
"entregaSabado": "N" 

) 
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Using Postman: 


GET v {{baseUrl}}/v1/nacional/:coProduto?cepOrigem=700029008&cepDestino=05311900 Er 


Params e Authorization Headers (8) Body Pre-request Script Tests Settings Cookies 





Query Params 


KEY VALUE DESCRIPTION co Bulk Edit 
cepOrigem 70002900 (Required) CEP de origem da postagem. 
cepDestino 05311900 (Required) CEP de destino da postagem. 


Path Variables 





KEY VALUE DESCRIPTION eco Bulk Edit 
coProduto 03220 (Required) Código do produto ou serviço 
Body Cookies (1) Headers (13) Test Results & Status: 200 OK Time: 87ms Size: 561B Save Response v 
Pretty Raw Preview Visualize JSON v ë 3 © Aa 
2 É l 
2 “coProduto": "03220", 
3 a 7 
4 "2022-03-22T23:58:00", 
5 “entregaDomiciliar": "S", 
6 “entregaSabado": "N" 





For the url base: https://apihom.correios.com.br/prazo/ using POST: /v1/nacional 





curl --location -- 

request POST 'https://apihom.correios.com.br/prazo/vl/nacional' \ 
--header 'Content-Type: application/json' \ 

--header 'Accept: application/json' \ 


QOFPIiwiBvc3RhZ2VtIjp7Im51bWVybyI6IjAwNzYzNj1I2MzkiLCJjb250cmFObyI6Ij... \ 
--data-raw '{ 
"idLote": "1", 
"parametrosPrazo": L 
{ 
"cepDestino": "70002900", 
"cepOrigem": "05311900", 
"coProduto": "04162", 
"nuRequisicao": "1", 
"dtEvento”: "18/03/2022" 


"cepDestino": "70002900", 
"sepOrigem": *05311900", 
"coProduto": "04668", 
"nuRequisicao": "2", 
"dtEvento”: "18/03/2022% 





header 'Authorization: Bearer eyJhbGciOiJSUzUxMiJ9.eyJhbWJpZW50ZSI6IkhPTU9IMTOdB 
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To obtain the following response: 





“eoProduto™: “O4162", 
"nukReguisicao": "1; 

"prazoEntrega": 1, 

“da taMaxima™:. “2022=03=21723:58:007, 
"entregaDomiciliar": "S", 


"entregaSabado": "N" 


"coProduto": "04669", 
"nuRequisicao"i "2", 

"prazoEntrega": 5, 

"dataMaxima": "2022-03-25T23:58:00", 
"entregaDomiciliar": "S", 


"entregaSabado": "N" 











Using Postman 


POST ~  ((baseUri))/v1/nacional EN 











Params Authorization Headers (11) Body @  Pre-request Script Tests Settings Cookies 
Ð none @ form-data O x-www-form-urlencoded @raw @ binary @GraphQL JSON v Beautify 
3 “parametrosPrazo": [ 
4 1 
5 “cepDestino”: "70002900", 
6 “cepOrigem": "05311900", 
7 "coProduto": "04162", 
8 “nuRequisicao": "1", 
9 "dtEvento": "18/03/2022" 
10 i, 
1 E 
12 | "cepDestino”: "70002900", — 
13 “cepOrigem": "95311900", 
14 “coProduto": "04669", 
15 “nuRequisicao": “2º, 
16 "dtEvento": "18/03/2022" 
17 B 
Body Cookies (1) Headers (13) Test Results ES Status: 200 OK Time: 98 ms Size:719B Save Response v 
Pretty Raw Preview Visualize JSON v = B Aa 


1 

2 

3 “coProduto”: "04162", 

4 “nuRequisicao": "1", 

5 “prazoEntrega": 1, 

6 “dataMaxima": “2022-03-21723:58:00" | 
7 “entregaDomiciliar": "S", 

8 “entregaSabado": "N 





9 CR 

10 H 

11 “coProduto”: "04669", 

12 “nuRequisicao": "2", 

13 “prazoEntrega”: 5, 

14 “dataMaxima": “2022-03-25T23:58:00", 
15 “entregaDomiciliar": "S", 

16 “entregaSabado": "N" 
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API Price 


For the url base: https://apihom.correios.com.br/preco we use GET: 
/v1/nacional/{codigoServico} 
For the request: 





curl --location -- 





request GET 'https://apihom.correios.com.br/preco/vl/nacional/03220?cepDestino=7 
19300008cep0Origem=709020008psObjeto=3004tp0bjeto=2&4comprimento=208largura=2048alt 
ura=208servicosAdicionais=01986servicosAdicionais=0018vlDeclarado=200'" A 

--header 'Accept: application/json' \ 

header ‘Authorization: Bearer eyJhbGciOiJSUzUxMiJ9.eyJhbWJpZW50ZSI6IkKhPTU9MTOdBO 
OFPLTiwiaWQi0iI1MzQ20DQOMDAWMDEZNCIsInBmbCI6I11BKTiwiY25wail61jUzNDY4NDQWMDAwMTMOI 
iwiY2FydGFVLXBvc3RhZ2VtIjp7Im51bWVybyI 61jAwNzYzNjI2MzkiLCJjb250cmFObyI61jk5MTIOM 
JAyOTIiLCJkcil6MTAsImFwaSI6WzOxXLDc2LDMOLDM2LDM1LDg3LDgzLDI2XX0sImlwIjoiMTAuO0C42N 
C42MSwxMC4z0C4WwLjASsMTAUOC42NC42MSIsImlhdCI6MTYONZY5MzkzOSwiaXNzIjoidG9IrZW4tc2Vyd 
ml1jZSTsImV4cCI6MTYONzc4MDMzOSwianRpIjoiN2ZmNTAOMGUtOWV] MSOONTAyLThjNGUtYZzM5Yzk30 
WYOOTNjIn0... 





























We have the following response: 





{ 
"eoBroduto"s "03220", 
"pcBase": "10,68", 
"pcBaseGeral": "11,13", 
"peVariacao": "0,0000", 
"pcReferencia": "11,13", 
“ylBaseCalculoImposto”: "19,92", 
"inPesoCubico"”: "N"; 
"psCobrado"¿ "300", 
"servicoAdicional": [ 
{ 
"coServAdicional": "019", 
"tpservAdicional": "y", 


"pcServicoAdicional": "1,79" 


"coServAdicional": "001", 
"tpServAdicional": "A", 


"peservicoAdicional": "7,00" 


1, 

"peAdValorem": "0,0100", 
"ylSeguroAutomatico": "21,00", 
latAdicional":. MO", 

Ie La s "1i ito; 
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“acraixaVariação"» "11,13%, 


"perroduto”. "ll. e 

















"poTotalseryicosAdicronais": "8,79", 
Terroir "LS, 920 
} 
On Postman: 
GET v  {{baseUr!}}/v1/nacional/:coProduto?cepDestino=71930000&cepOrigem=70902000&psObjeto=300&tpObjeto=2&compriment 
Params e Authorization Headers (8) Body Pre-request Script Tests Settings Cookies 
= careen mana vv: 
O aut 
O jo na E 
viDeclarado 200 
() itEve J 
TT nint ffici 
Key a Yescription 
Path Variables 
KEY VALUE DESCRIPTION eco Bulk Edit 
coProduto 03220 (Required) Código do produto ou servigo 


Body Cookies (1) Headers (13) Test Results (ES Status: 200 OK Time: 335ms Size: 978 B Save Response v 





Pretty Raw Preview Visualize JSON v =) DA 
1 É 
2 “coProduto": "03220", 
3 "pcBase”: "10,68", 
4 "pcBaseGeral”: "11,13", l 
5 “peVariacao": "0,0000", 
6 "pcReferencia”: "11,13", | 
7 “vlBaseCalculoImposto": "19,92", 
8 "inPesoCubico”: "N", 
9 “psCobrado": "300", 
10 “servicoAdicional": L 
11 { 
12 “coServAdicional": "019", 
13 “tpServAdicional”: "V", | 
14 “pcServicoAdicional”: "1,79" 
15 H 
16 H 
17 “coServAdicional”: "001", 
18 "tpServAdicional”: "A", 
19 “pcServicoAdicional": "7,90" 








we use POST. For 


https://apihom.correios.com.br/preco and with POST: /v1/nacional 


For pricing up to 5 simulations, the url base: 





curl --location -- 


request POST 


"https://apihom.correios.com.br/preco/vl/nacional' A 


--header 
--header 
--header 


"Content-Type: application/json' \ 
"Accept: application/json' \ 


"Authorization: 


--data-raw ' 
"idLote": 





"parametro 


Bearer eyJhbGciOiJSUzUxMigJ9.... A 
d 
wi De 


sProduto": [ 
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"04162", 
“"nuRequisição": "1", 
"70902000", 
SOU", 
non, 
"comprimento": "20", 
eo”, 
20", 
"servicosAdicionais": II 
1, 
"vlDeclarado": "100", 
"dtEvénte": “Leso3y 2022"; 
"71930000" 


"cobroduto": 
"cepOrigem": 
"psObjeto": 


"tpObjeto": 


"largura": 


"altura": 


1%) 





"cepDestino": 
},{ 
"coProduto": "04162", 
"aurequisigao”: 11"; 
"70902000", 


1300". 


"cepOrigem": 
"psObjeto": 
"EpoObjeto": "2", 
"comprimento": "20", 
Su, 
"20", 
"servicosAdicionais": II 
l, 
"vlDeclarado": "100", 
“dtivento”: "18/03/2022", 
"71930000" 


"Largura": 


"altura": 


e 





"cepDestino": 


] 
) 1 





"coServAdicional":"019"), 


“coServAdicional™:"019"}, 


{"coServAdicional": 


{"coServAdicional": 


NOD 


NOD 





We have the following response: 





L { 
“coProduto” : 
"pcBase": 
"pcBaseGeral": 
"peVariacao": 


"pcReferencia": 
"nuRequisicao": 


"inPesoCubico": 


"psCobrado": 


{ 





"coServAdicional": 


"94162"; 
WO Toy 
"Iopa, 
"0, 
"LO; LA: 
"vlBaseCalculoImposto": 
"mim, 
"N", 
“300”, 


"servicoAdicional": [ 


0000", 


14,008, 


"O19"; 
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"EpbsetvAdicional": "y", 


"pesServicoAdicional”: "0,79" 


"coServAdicional": "001", 
"tpServAdicional": "A", 


"peServicoAdicional”": "7,00" 


l; 

"peAdValorem": "0,0100", 
"vlSeguroAutomatico": "21,00", 
"qrAdicional"s “OM, 

TpaFarxa": LO, ia", 
“peraixaVariagao”"i "10,14", 
“peProduce™: "LO, La", 
"pcTotalServicosAdicionais": "7,79", 
perales 17 oa" 


"coProduto": "O4l6é2™, 
Wagener "9,731, 
"pcBaseGeral": "10,14", 
"peVariacao": "0,0000", 
"pcReferencia": "10,14", 
"vlBaseCalculolmposto": "17,93", 
"núRequisicao": "1", 
"inPesoCubico": "N", 
“"psCobrado": "300", 
"servicoAdicional": [ 
{ 
"coServAdicional": "019", 
"tpServAdicional": "y", 
"peservicoñAdiciohal":; "0,79% 


"coServAdicional": "001", 
"tpServAdicional": "A", 


"peServicoddicional": "7,00" 


l; 

"peAdValorem": "0,0100", 
"vlSeguroAutomatico": "21,00", 
"qrAdicional"s “OM, 

"tpebñaixa"s "1014"; 
“polaixaVariação": "10,14", 
“peProduto”: "10, 14%, 
"peTotalSérvicosAdicionais": "9,79", 
“pekina: MI ro" 





D 
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On Postman 


POST v  {{baseUr!}}/v1/nacional 





Params Authorization Headers (11) Body e Pre-request Script Tests Settings Cookies 
@ none Z form-data Z x-www-form-urlencoded Z raw O binary @ GraphQL JSON v Beautify 

+ + 

2 “idLote":-"4", 

3 “parametrosProduto": [ 

4 i 

5 “coProduto": "04162", 

6 “nuRequisicao": "1", 

7 “cepOrigem":- "70902000", 

8 "psObjeto”: "300", 

9 "tpobjeto": "2", 





10 "comprimento": "20", 
11 "largura": "20", 
12 “altura”: "20", 
13 “servicosAdicionais": LZ “coServAdicional":"019"}, {"coServAdicional":"@01"} ], 
14 “vlDeclarado": "100", 
15 “dtEvento": "18/03/2022", 
16 "cepDestino”: "71930000" 
17 1.5 T 
18 “coProduto": "04162", 
Body Cookies (1) Headers (13) Test Results €&% Status: 200 OK Time: 503ms Size: 1.51 KB Save Response v 
Pretty Raw Preview Visualize JSON v =a DA 
1 [ L 
2 | F 
3 "coProduto”: "04162", 
4 “pcBase": "9,73", 
5 “peBaseGeral": "10,14" | 
6 "peVariacao": "0,0000", 
vd “pcReferencia": "10,14", 
8 “vlBaseCalculoImposto": "17,93", 
9 “nuRequisicao": "1", 
10 “inPesoCubico": "N", 
11 "psCobrado”: "300", 
12 “servicoAdicional": [ 
13 i 
14 “coServadicional": "019", 
15 “tpServAdicional”: "vV", 
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12. API Rastro (Tracking API) 


This API allows querying the status of the object within the postal flow. The tab of 
this API will be: 


Api Manager - Token (5) x SRO - Rastro (87) x 


Rastro 


https://apihom.correios.com_br/srorastro/v3/api-docs 


Permitir o rastreamento de objetos por código de objeto ou por uma lista de objetos ou por CPF/CNPJ 


Rastreamento Externo 








GET /v1/objetos/{codigoObjeto} Rastreamento de Objeto 
GET /v1/objetos Rastreamento de Objeto 
GET /vl/objetos/rastrosdocumento Rastreamento de Objeto 











As with the other APIs, a base url is used: https://apphom.correios.com.br/rastro with 
the GET: /v1/objetos/{codigoObjeto} 





Examples of objects: DG049186230BR, DG049186226BR e DG049186212BR 











Making the request: 





curl --location -- 

request GET 'https://apihom.correios.com.br/srorastro/vl/objetos/DG049186226BR?r 
esultado=T' À 

--header ‘Accept: application/json' A 

--header 'Authorization: Bearer eyJhbGciOiJSUZUxMiJ9.... 











Receiving the response: 





{ 


"“versao"i "Isg T"; 








"quantidade": 1, 
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"resultado": "Todos os Eventos", 
"objetos": [ 
{ 
"codObjeto": "DG049186226BR", 
“EtpoPostel”: 4 
tigla"; "DGT, 
"descricao": "ENCOMENDA SEDEX (ETIQ LOGICA)", 
"categoria": "SEDEX" 
}, 
"dtPrevista": "2022-03-11T20:58:00", 
"modalidade": "EP", 
"peso": 0.5, 
"formato": "Pacote", 
"eventos": | 
{ 
"eodigo":+ "BDE", 
"Eipo™t: CDL”, 
"dtHrcriado": "2022-03-11 T17:03:00", 
"descricao": "Objeto entregue ao destinatário", 
"unidade": { 
"tipo": "Unidade de Atendimento", 
"endereco": 1 
NUE: TACH; 
"cidade": "XAPURI" 
) 
) 
}, 
{ 
"codigo": “"QEC", 
w E Ey Moat 
WS Ra T T "2022=053=1] 117402448", 
"descricao": "Objeto em rota de entrega", 
"detalhe": "Aguarde envio de link para acompanhar a entrega 
em tempo real\r\n", 
"unidade": { 
"tipo": "Unidade de Tratamento", 
“endereco”: / 
Woes SE, 
"cidade": "SAO PAULO" 
) 
) 
}, 
{ 
“codigo”: NRO", 
HEL: "Ole, 
"dtHeCriado": "2022-03-=11717:02:35", 
"descricao": "Objeto em tránsito", 
"detalhe": "Por favor, aguarde", 
"unidade": { 
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"endereco": { 


"cidade": 


}, 


"unidadeDestino": 


"endereco": { 


"cidade": 


"sodigo": "PO", 


"Elpo": “Oa 


"unidade": { 


"endereco": { 


"cidade": 





"uf": DET. 


"tipo": "Unidade de Distribuição", 


"BRASILIA" 


{ 


"uf": “Cor; 


"APAR 





"uf": som. 


"tipo": "Unidade de Tratamento", 


ECIDA DE GOIANIA" 


"dtHrcriado": "2022-=03-=10T19:10:<36", 


"descricao": "Objeto postado", 


"tipo": "Unidade de Atendimento", 


"SAO PAULO” 
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13. Final considerations 

This material was developed to make it easier for the reader who was used to the 
Correios Web Services, which had a SOAP XML standard, and may miss the explanatory 
material that was provided for each system, with the migration to REST. With the Correios 
API, we centralized the documentation and as the update is dynamic, it is recommended 
that you return frequently. 

For all APIs mentioned in this material, they are the ones that are released for use. 
Thus, if you have questions regarding the API, the procedure is to contact the Commercial 
Assistant of your region or Contract. 

Service information can be obtained from our website: 


https://www.correios.com.br/falecomoscorreios/central-de-atendimento 
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